/*
 * Copyright 2008 The Apache Software Foundation Licensed under the Apache
 * License, Version 2.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
 * or agreed to in writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the specific language
 * governing permissions and limitations under the License.
 */

package org.apache.ibatis.ibator.api;

/**
 * This interface can be implemented to return progress information from the
 * file generation process. During the execution of code generation, there are
 * three main operations: database introspection, code generation based on the
 * results of introspection, and then merging/saving generated files. Ibator
 * will call methods in this interface accordingly and in this order:
 * <ol>
 * <li>introspectionStarted(int)</li>
 * <li>(Repeatedly) startTask(String)</li>
 * <li>generationStarted(int)</li>
 * <li>(Repeatedly) startTask(String)</li>
 * <li>saveStarted(int)</li>
 * <li>(Repeatedly) startTask(String)</li>
 * <li>done()</li>
 * </ol>
 * <p>
 * Periodically, Ibator will call <code>checkCancel()</code> to see if the
 * method should be canceled.
 * <p>
 * For planning purposes, the most common use case will have a ratio of 20%
 * instrospection tasks, 40% generation tasks, and 40% save tasks.
 * 
 * @author Jeff Butler
 */
public interface ProgressCallback
{
	/**
	 * Called to note the start of the introspection phase, and to note the
	 * maximum number of startTask messages that will be sent for the
	 * introspection phase.
	 * 
	 * @param totalTasks
	 *            the maximum number of times startTask will be called for the
	 *            introspection phase.
	 */
	void introspectionStarted(int totalTasks);

	/**
	 * Called to note the start of the generation phase, and to note the maximum
	 * number of startTask messages that will be sent for the generation phase.
	 * 
	 * @param totalTasks
	 *            the maximum number of times startTask will be called for the
	 *            generation phase.
	 */
	void generationStarted(int totalTasks);

	/**
	 * Called to note the start of the file saving phase, and to note the
	 * maximum number of startTask messages that will be sent for the file
	 * saving phase phase.
	 * 
	 * @param totalTasks
	 *            the maximum number of times startTask will be called for the
	 *            file saving phase.
	 */
	void saveStarted(int totalTasks);

	/**
	 * Called to denote the beginning of a save task
	 * 
	 * @param taskName
	 *            a descriptive name of the current work step
	 */
	void startTask(String taskName);

	/**
	 * Ibator calls this method when all generated files have been saved
	 */
	void done();

	/**
	 * Ibator will call this method periodically during a long running method.
	 * If the the implementation throws <code>InterruptedException</code> then
	 * the method will be canceled. Any files that have already been saved will
	 * remain on the file system.
	 * 
	 * @throws InterruptedException
	 *             if the operation should be halted
	 */
	void checkCancel() throws InterruptedException;
}
